Help for ListCache v1.09 (01 Jan 2020)
======================================

This is a simple little program to produce statistics on the
Netsurf Disc Cache, and also an Obey file which if run will
delete all empty directories in the cache.

It was really written for my own use, and so is a little crude,
but may be useful for others.

Any feedback welcome - especially any results!

Please send me the List file from the first time you run it,
and I can explain anything you do not understand.

Martin Avison
riscos@avisoft.f9.co.uk


Processing
==========

ListCache is probably best run when Netsurf is not running.
It only *reads* the cache - it makes no changes!
Note that it can take a long time to run!
There can easily be 50k+ directories.

When ListCache is run it will ...

- Read Choices:WWW.Netsurf.Choices to extract your current disc
  cache size and expiry age.

- Read all directory entries contained in <Cache$Dir>.Netsurf.
  This does multi-task, but may take some considerable time!
  During this time the hourglass will be displayed, with an
  approximate percentage complete.

- When complete, the output directory and List file will be displayed.

Output
======

All output files are created in !ListCache.Out directory.
The List and Wipe filenames include the date to make it
easy to keep old versions for reference if you wish.

The List text file shows ...
- your Netsurf Choices values for the disc cache.
- a File Summary showing numbers and sizes of files over each
  age band, which are multiples of the Expiry Days.
- a Directory Summary showing the total, used and empty
  directories. Note on VRPC the directory space is not available.
- a list up to 50 of the files in theoldest age band.
- the time taken to read all the directory entries.

A Summary text file will also be created, if it does not exist.
A single line will be added at the end containing the date,
Cache Size and expiry days, Total files & size, and the number
of directories Used and Empty.

The Wipe Obey file is a simple list of Wipe commands which,
if run, will delete all empty directories, and when complete it will
add to  Summaries an "Empty Directories Deleted" line.
Note that Wipe will not delete a directory with any contents, so the
file is ordered so that lower-level directories are deleted first.
This can be run at your own risk, but seems to cause no problems.
It may be best to run in a task window ... it can take some time!

Notes on Usage
==============

It is useful to have the results over a period of time, so ListCache
can be automatically run every <Expiry Days> using the Task Alarm
facilities of Organizer or Alarm.

Netsurf prunes the cache only when adding a new entry causes the
overall cache usage to exceed the set maximum level. At that point
the least "valuable" objects are discarded untill the size drops
below the desired size. This process is subject to 10% hysteresis
to avoid excessive thrashing. It is not clear how "valuable" is
calculated, or how the expiry date is used.

Netsurf never deletes cache directories, even when all files contained
have been deleted, but it is safe to manually delete empty directories.
This can be done easily by using the generated Wipe obey file.

There is no known way to safely delete old files manually.

History
=======
v1.00 (27 Apr 2018)   Initial release
v1.01 (27 Apr 2018)   Catered for BASIC < v1.30
                      Added hourglass
v1.02 (30 Apr 2018)   Made more flexible
v1.03 ( 7 Feb 2019)   Added Summary
v1.04 (13 Apr 2019)   Added summary to Wipes.
v1.05 (28 Dec 2019)   Catered for no disc cache defined.
                      Catered for no DIM LOCAL in ROL BASIC v1.37
v1.06 (29 Dec 2019)   Fixed several possible zerodivides.
v1.07 (31 Dec 2019)   Fixed initial Summary.
                      Big File Summary changes.
                      Changed oldest file list radically.
v1.08 (31 Dec 2019)   Fixed no files stored.
v1.09 (01 Jan 2020)   Improved file handle checks.
